home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / fmtmsg.z / fmtmsg
Text File  |  1998-10-20  |  17KB  |  265 lines
  1.  
  2.  
  3.  
  4. ffffmmmmttttmmmmssssgggg((((1111))))                                                            ffffmmmmttttmmmmssssgggg((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _ffff_mmmm_tttt_mmmm_ssss_gggg - display a message on _ssss_tttt_dddd_eeee_rrrr_rrrr or system console
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _ffff_mmmm_tttt_mmmm_ssss_gggg [_----_cccc _c_l_a_s_s] [_----_uuuu _s_u_b_c_l_a_s_s] [_----_llll _l_a_b_e_l] [_----_ssss _s_e_v_e_r_i_t_y] [_----_tttt _t_a_g] [_----_aaaa
  13.      _a_c_t_i_o_n]  _t_e_x_t
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      Based on a message's classification component, _ffff_mmmm_tttt_mmmm_ssss_gggg either writes a
  17.      formatted message to _ssss_tttt_dddd_eeee_rrrr_rrrr or writes a formatted message to the console.
  18.  
  19.      A formatted message consists of up to five standard components as defined
  20.      below.  The classification and subclass components are not displayed as
  21.      part of the standard message, but rather define the source of the message
  22.      and direct the display of the formatted message.  The valid options are:
  23.  
  24.      _----_cccc _c_l_a_s_s    Describes the source of the message.  Valid keywords are:
  25.  
  26.                      _hhhh_aaaa_rrrr_dddd      The source of the condition is hardware.
  27.                      _ssss_oooo_ffff_tttt      The source of the condition is software.
  28.                      _ffff_iiii_rrrr_mmmm      The source of the condition is firmware.
  29.  
  30.      _----_uuuu _s_u_b_c_l_a_s_s A list of keywords (separated by commas) that further defines
  31.                  the message and directs the display of the message.  Valid
  32.                  keywords are:
  33.  
  34.                      _aaaa_pppp_pppp_llll      The condition originated in an application.
  35.                                This keyword should not be used in combination
  36.                                with either _uuuu_tttt_iiii_llll or _oooo_pppp_ssss_yyyy_ssss.
  37.                      _uuuu_tttt_iiii_llll      The condition originated in a utility.  This
  38.                                keyword should not be used in combination with
  39.                                either _aaaa_pppp_pppp_llll or _oooo_pppp_ssss_yyyy_ssss.
  40.                      _oooo_pppp_ssss_yyyy_ssss     The message originated in the kernel.  This
  41.                                keyword should not be used in combination with
  42.                                either _aaaa_pppp_pppp_llll or _uuuu_tttt_iiii_llll.
  43.                      _rrrr_eeee_cccc_oooo_vvvv     The application will recover from the
  44.                                condition.  This keyword should not be used in
  45.                                combination with _nnnn_rrrr_eeee_cccc_oooo_vvvv.
  46.                      _nnnn_rrrr_eeee_cccc_oooo_vvvv    The application will not recover from the
  47.                                condition.  This keyword should not be used in
  48.                                combination with _rrrr_eeee_cccc_oooo_vvvv.
  49.                      _pppp_rrrr_iiii_nnnn_tttt     Print the message to the standard error stream
  50.                                _ssss_tttt_dddd_eeee_rrrr_rrrr.
  51.                      _cccc_oooo_nnnn_ssss_oooo_llll_eeee   Write the message to the system console.
  52.                                _pppp_rrrr_iiii_nnnn_tttt, _cccc_oooo_nnnn_ssss_oooo_llll_eeee, or both may be used.
  53.  
  54.      _----_llll _l_a_b_e_l    Identifies the source of the message.
  55.  
  56.      _----_ssss _s_e_v_e_r_i_t_y Indicates the seriousness of the error.  The keywords and
  57.                  definitions of the standard levels of _s_e_v_e_r_i_t_y are:
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ffffmmmmttttmmmmssssgggg((((1111))))                                                            ffffmmmmttttmmmmssssgggg((((1111))))
  71.  
  72.  
  73.  
  74.                      _hhhh_aaaa_llll_tttt      The application has encountered a severe fault
  75.                                and is halting.
  76.                      _eeee_rrrr_rrrr_oooo_rrrr     The application has detected a fault.
  77.                      _wwww_aaaa_rrrr_nnnn      The application has detected a condition that
  78.                                is out of the ordinary and might be a problem.
  79.                      _iiii_nnnn_ffff_oooo      The application is providing information about
  80.                                a condition that is not in error.
  81.  
  82.      _----_tttt _t_a_g      The string containing an identifier for the message.
  83.  
  84.      _----_aaaa _a_c_t_i_o_n   A text string describing the first step in the error recovery
  85.                  process.  This string must be written so that the entire
  86.                  _a_c_t_i_o_n argument is interpreted as a single argument.  _ffff_mmmm_tttt_mmmm_ssss_gggg
  87.                  precedes each action string with the _TTTT_OOOO _FFFF_IIII_XXXX_:::: prefix.
  88.  
  89.      _t_e_x_t        A text string describing the condition.  Must be written so
  90.                  that the entire _t_e_x_t argument is interpreted as a single
  91.                  argument.
  92.  
  93.      The environment variables _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB and _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL control the behavior of
  94.      _ffff_mmmm_tttt_mmmm_ssss_gggg.  _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is set by the administrator in the _////_eeee_tttt_cccc_////_pppp_rrrr_oooo_ffff_iiii_llll_eeee for the
  95.      system.  Users can override the value of _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB set by the system by
  96.      resetting _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB in their own _...._pppp_rrrr_oooo_ffff_iiii_llll_eeee files or by changing the value in
  97.      their current shell session.  _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL can be used in shell scripts.
  98.  
  99.      _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB tells _ffff_mmmm_tttt_mmmm_ssss_gggg which message components to select when writing
  100.      messages to _ssss_tttt_dddd_eeee_rrrr_rrrr.  The value of _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is a colon separated list of
  101.      optional keywords.  _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB can be set as follows:
  102.  
  103.            _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB_====[_k_e_y_w_o_r_d[_::::_k_e_y_w_o_r_d[_::::. . .]]]
  104.            _eeee_xxxx_pppp_oooo_rrrr_tttt _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB
  105.  
  106.      Valid _k_e_y_w_o_r_d_s are:  _llll_aaaa_bbbb_eeee_llll, _ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy, _tttt_eeee_xxxx_tttt, _aaaa_cccc_tttt_iiii_oooo_nnnn, and _tttt_aaaa_gggg.  If _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB
  107.      contains a keyword for a component and the component's value is not the
  108.      component's null value, _ffff_mmmm_tttt_mmmm_ssss_gggg includes that component in the message
  109.      when writing the message to _ssss_tttt_dddd_eeee_rrrr_rrrr.  If _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB does not include a
  110.      keyword for a message component, that component is not included in the
  111.      display of the message.  The keywords may appear in any order.  If
  112.      _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is not defined, if its value is the null string, if its value is
  113.      not of the correct format, or if it contains keywords other than the
  114.      valid ones listed above, _ffff_mmmm_tttt_mmmm_ssss_gggg selects all components.
  115.  
  116.      _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB affects only which message components are selected for display.
  117.      All message components are included in console messages.
  118.  
  119.      _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL defines severity levels and associates print strings with them
  120.      for use by _ffff_mmmm_tttt_mmmm_ssss_gggg.  The standard severity levels shown below cannot be
  121.      modified.  Additional severity levels can be defined, redefined, and
  122.      removed.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ffffmmmmttttmmmmssssgggg((((1111))))                                                            ffffmmmmttttmmmmssssgggg((((1111))))
  137.  
  138.  
  139.  
  140.           _0000   (no severity is used)
  141.           _1111   HALT
  142.           2   ERROR
  143.           3   WARNING
  144.           4   INFO
  145.  
  146.      _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL is set as follows:
  147.  
  148.           _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL_====[_d_e_s_c_r_i_p_t_i_o_n[_::::_d_e_s_c_r_i_p_t_i_o_n[_::::...]]]
  149.           _eeee_xxxx_pppp_oooo_rrrr_tttt _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL
  150.  
  151.      _d_e_s_c_r_i_p_t_i_o_n is a comma-separated list containing three fields:
  152.  
  153.           _d_e_s_c_r_i_p_t_i_o_n_====_s_e_v_e_r_i_t_y__k_e_y_w_o_r_d_,,,,_l_e_v_e_l_,,,,_p_r_i_n_t_s_t_r_i_n_g
  154.  
  155.      _s_e_v_e_r_i_t_y__k_e_y_w_o_r_d is a character string used as the keyword with the _----_ssss
  156.      _s_e_v_e_r_i_t_y option to _ffff_mmmm_tttt_mmmm_ssss_gggg.
  157.  
  158.      _l_e_v_e_l is a character string that evaluates to a positive integer (other
  159.      than _0000, _1111, _2222, _3333, or _4444, which are reserved for the standard severity
  160.      levels).  If the keyword _s_e_v_e_r_i_t_y__k_e_y_w_o_r_d is used, _l_e_v_e_l is the severity
  161.      value passed on to _ffff_mmmm_tttt_mmmm_ssss_gggg(3C).
  162.  
  163.      _p_r_i_n_t_s_t_r_i_n_g is the character string used by _ffff_mmmm_tttt_mmmm_ssss_gggg in the standard
  164.      message format whenever the severity value _l_e_v_e_l is used.
  165.  
  166.      If _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL is not defined, or if its value is null, no severity levels
  167.      other than the defaults are available.  If a _d_e_s_c_r_i_p_t_i_o_n in the colon
  168.      separated list is not a comma separated list containing three fields, or
  169.      if the second field of a comma separated list does not evaluate to a
  170.      positive integer, that _d_e_s_c_r_i_p_t_i_o_n in the colon separated list is
  171.      ignored.
  172.  
  173. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  174.      The exit codes for _ffff_mmmm_tttt_mmmm_ssss_gggg are the following:
  175.  
  176.           _0000    All the requested functions were executed successfully.
  177.  
  178.           _1111    The command contains a syntax error, an invalid option, or an
  179.                invalid argument to an option.
  180.  
  181.           _2222    The function executed with partial success, however the message
  182.                was not displayed on _ssss_tttt_dddd_eeee_rrrr_rrrr.
  183.  
  184.           _4444    The function executed with partial success, however the message
  185.                was not displayed on the system console.
  186.  
  187.           _3333_2222   No requested functions were executed successfully.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ffffmmmmttttmmmmssssgggg((((1111))))                                                            ffffmmmmttttmmmmssssgggg((((1111))))
  203.  
  204.  
  205.  
  206. EXAMPLES
  207.      Example 1:  The following example of _ffff_mmmm_tttt_mmmm_ssss_gggg produces a complete message
  208.      in the standard message format and displays it to the standard error
  209.      stream:
  210.  
  211.           _ffff_mmmm_tttt_mmmm_ssss_gggg _----_cccc _ssss_oooo_ffff_tttt _----_uuuu _rrrr_eeee_cccc_oooo_vvvv_,,,,_pppp_rrrr_iiii_nnnn_tttt_,,,,_aaaa_pppp_pppp_llll _----_llll _UUUU_XXXX_::::_cccc_aaaa_tttt _----_ssss _eeee_rrrr_rrrr_oooo_rrrr _----_tttt _UUUU_XXXX_::::_cccc_aaaa_tttt_::::_0000_0000_1111
  212.           _----_aaaa _""""_rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll_"""" _""""_iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx_""""
  213.  
  214.      produces:
  215.  
  216.           UX:cat: ERROR: invalid syntax
  217.           TO FIX: refer to manual   UX:cat:138
  218.  
  219.      Example 2:  When the environment variable _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB is set as follows:
  220.  
  221.           _MMMM_SSSS_GGGG_VVVV_EEEE_RRRR_BBBB_====_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy_::::_tttt_eeee_xxxx_tttt_::::_aaaa_cccc_tttt_iiii_oooo_nnnn
  222.  
  223.      and Example 1 is used, _ffff_mmmm_tttt_mmmm_ssss_gggg produces:
  224.  
  225.           ERROR: invalid syntax
  226.           TO FIX: refer to manual
  227.  
  228.      Example 3:  When the environment variable _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL is set as follows:
  229.  
  230.           _SSSS_EEEE_VVVV______LLLL_EEEE_VVVV_EEEE_LLLL_====_nnnn_oooo_tttt_eeee_,,,,_5555_,,,,_NNNN_OOOO_TTTT_EEEE
  231.  
  232.      the following _ffff_mmmm_tttt_mmmm_ssss_gggg command:
  233.  
  234.           _ffff_mmmm_tttt_mmmm_ssss_gggg _----_cccc _ssss_oooo_ffff_tttt _----_uuuu _pppp_rrrr_iiii_nnnn_tttt _----_llll _UUUU_XXXX_::::_cccc_aaaa_tttt _----_ssss _nnnn_oooo_tttt_eeee _----_aaaa _""""_rrrr_eeee_ffff_eeee_rrrr _tttt_oooo _mmmm_aaaa_nnnn_uuuu_aaaa_llll_""""
  235.           _""""_iiii_nnnn_vvvv_aaaa_llll_iiii_dddd _ssss_yyyy_nnnn_tttt_aaaa_xxxx_""""
  236.  
  237.      produces:
  238.  
  239.           UX:cat: NOTE: invalid syntax
  240.           TO FIX: refer to manual
  241.  
  242.      and displays the message on _ssss_tttt_dddd_eeee_rrrr_rrrr.
  243.  
  244. NNNNOOOOTTTTEEEESSSS
  245.      A slightly different standard error message format and a new developer
  246.      interface, pfmt, is being introduced as the replacement for fmtmsg.  A
  247.      similar interface, lfmt, is also being introduced for producing a
  248.      standard format message and forwarding messages to the console and/or to
  249.      the system message logging and monitoring facilities.  fmtmsg will be
  250.      removed at a future time.
  251.  
  252. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  253.      _aaaa_dddd_dddd_ssss_eeee_vvvv_eeee_rrrr_iiii_tttt_yyyy(3C), _ffff_mmmm_tttt_mmmm_ssss_gggg(3C)
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.